<!DOCTYPE html>
<html lang="en-us">
  <head>

    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    
<meta charset="UTF-8">
<title>Index-level shard allocation filtering | Elasticsearch Guide [7.7] | Elastic</title>
<link rel="home" href="index.html" title="Elasticsearch Guide [7.7]">
<link rel="up" href="index-modules-allocation.html" title="Index Shard Allocation">
<link rel="prev" href="index-modules-allocation.html" title="Index Shard Allocation">
<link rel="next" href="delayed-allocation.html" title="Delaying allocation when a node leaves">
<meta name="DC.type" content="Learn/Docs/Elasticsearch/Reference/7.7">
<meta name="DC.subject" content="Elasticsearch">
<meta name="DC.identifier" content="7.7">
<meta name="robots" content="noindex,nofollow">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <script src="https://cdn.optimizely.com/js/18132920325.js"></script>
    <link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
    <link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
    <link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
    <link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
    <link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
    <link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
    <link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
    <link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
    <link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
    <link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
    <link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
    <link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
    <link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
    <link rel="manifest" href="/manifest.json">
    <meta name="apple-mobile-web-app-title" content="Elastic">
    <meta name="application-name" content="Elastic">
    <meta name="msapplication-TileColor" content="#ffffff">
    <meta name="msapplication-TileImage" content="/mstile-144x144.png">
    <meta name="theme-color" content="#ffffff">
    <meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd">
    <meta name="yandex-verification" content="d8a47e95d0972434">
    <meta name="localized" content="true">
    <meta name="st:robots" content="follow,index">
    <meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png">
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
    <link rel="icon" href="/favicon.ico" type="image/x-icon">
    <link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
    <link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
    <link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
    <link rel="stylesheet" type="text/css" href="/guide/static/styles.css">
  </head>

  <!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->

  <body>
    <!-- Google Tag Manager -->
    <script>dataLayer = [];</script><noscript><iframe src="//www.googletagmanager.com/ns.html?id=GTM-58RLH5" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
    <script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= '//www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); })(window,document,'script','dataLayer','GTM-58RLH5');</script>
    <!-- End Google Tag Manager -->

    <!-- Global site tag (gtag.js) - Google Analytics -->
    <script async src="https://www.googletagmanager.com/gtag/js?id=UA-12395217-16"></script>
    <script>
      window.dataLayer = window.dataLayer || [];
      function gtag(){dataLayer.push(arguments);}
      gtag('js', new Date());
      gtag('config', 'UA-12395217-16');
    </script>

    <!--BEGIN QUALTRICS WEBSITE FEEDBACK SNIPPET-->
    <script type="text/javascript">
      (function(){var g=function(e,h,f,g){
      this.get=function(a){for(var a=a+"=",c=document.cookie.split(";"),b=0,e=c.length;b<e;b++){for(var d=c[b];" "==d.charAt(0);)d=d.substring(1,d.length);if(0==d.indexOf(a))return d.substring(a.length,d.length)}return null};
      this.set=function(a,c){var b="",b=new Date;b.setTime(b.getTime()+6048E5);b="; expires="+b.toGMTString();document.cookie=a+"="+c+b+"; path=/; "};
      this.check=function(){var a=this.get(f);if(a)a=a.split(":");else if(100!=e)"v"==h&&(e=Math.random()>=e/100?0:100),a=[h,e,0],this.set(f,a.join(":"));else return!0;var c=a[1];if(100==c)return!0;switch(a[0]){case "v":return!1;case "r":return c=a[2]%Math.floor(100/c),a[2]++,this.set(f,a.join(":")),!c}return!0};
      this.go=function(){if(this.check()){var a=document.createElement("script");a.type="text/javascript";a.src=g;document.body&&document.body.appendChild(a)}};
      this.start=function(){var a=this;window.addEventListener?window.addEventListener("load",function(){a.go()},!1):window.attachEvent&&window.attachEvent("onload",function(){a.go()})}};
      try{(new g(100,"r","QSI_S_ZN_emkP0oSe9Qrn7kF","https://znemkp0ose9qrn7kf-elastic.siteintercept.qualtrics.com/WRSiteInterceptEngine/?Q_ZID=ZN_emkP0oSe9Qrn7kF")).start()}catch(i){}})();
    </script><div id="ZN_emkP0oSe9Qrn7kF"><!--DO NOT REMOVE-CONTENTS PLACED HERE--></div>
    <!--END WEBSITE FEEDBACK SNIPPET-->

    <div id="elastic-nav" style="display:none;"></div>
    <script src="https://www.elastic.co/elastic-nav.js"></script>

    <!-- Subnav -->
    <div>
      <div>
        <div class="tertiary-nav d-none d-md-block">
          <div class="container">
            <div class="p-t-b-15 d-flex justify-content-between nav-container">
              <div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="main-container">
      <section id="content">
        <div class="content-wrapper">

          <section id="guide" lang="en">
            <div class="container">
              <div class="row">
                <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                  <!-- start body -->
                  <div class="page_header">
<strong>IMPORTANT</strong>: No additional bug fixes or documentation updates
will be released for this version. For the latest information, see the
<a href="../current/index.html">current release documentation</a>.
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="index-modules.html">Index modules</a></span>
»
<span class="breadcrumb-link"><a href="index-modules-allocation.html">Index Shard Allocation</a></span>
»
<span class="breadcrumb-node">Index-level shard allocation filtering</span>
</div>
<div class="navheader">
<span class="prev">
<a href="index-modules-allocation.html">« Index Shard Allocation</a>
</span>
<span class="next">
<a href="delayed-allocation.html">Delaying allocation when a node leaves »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="shard-allocation-filtering"></a>Index-level shard allocation filtering<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/index-modules/allocation/filtering.asciidoc">edit</a>
</h2>
</div></div></div>
<p>You can use shard allocation filters to control where Elasticsearch allocates shards of
a particular index. These per-index filters are applied in conjunction with
<a class="xref" href="modules-cluster.html#cluster-shard-allocation-filtering" title="Cluster-level shard allocation filtering">cluster-wide allocation filtering</a> and
<a class="xref" href="modules-cluster.html#shard-allocation-awareness" title="Shard allocation awareness">allocation awareness</a>.</p>
<p>Shard allocation filters can be based on custom node attributes or the built-in
<code class="literal">_name</code>, <code class="literal">_host_ip</code>, <code class="literal">_publish_ip</code>, <code class="literal">_ip</code>, <code class="literal">_host</code> and <code class="literal">_id</code> attributes.
<a class="xref" href="index-lifecycle-management.html" title="ILM: Manage the index lifecycle">Index lifecycle management</a> uses filters based
on custom node attributes to determine how to reallocate shards when moving
between phases.</p>
<p>The <code class="literal">cluster.routing.allocation</code> settings are dynamic, enabling live indices to
be moved from one set of nodes to another. Shards are only relocated if it is
possible to do so without breaking another routing constraint, such as never
allocating a primary and replica shard on the same node.</p>
<p>For example, you could use a custom node attribute to indicate a node’s
performance characteristics and use shard allocation filtering to route shards
for a particular index to the most appropriate class of hardware.</p>
<h4>
<a id="index-allocation-filters"></a>Enabling index-level shard allocation filtering<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/index-modules/allocation/filtering.asciidoc">edit</a>
</h4>
<p>To filter based on a custom node attribute:</p>
<div class="olist orderedlist">
<ol class="orderedlist">
<li class="listitem">
<p>Specify the filter characteristics with a custom node attribute in each
node’s <code class="literal">elasticsearch.yml</code> configuration file. For example, if you have <code class="literal">small</code>,
<code class="literal">medium</code>, and <code class="literal">big</code> nodes, you could add a <code class="literal">size</code> attribute to filter based
on node size.</p>
<div class="pre_wrapper lang-yaml">
<pre class="programlisting prettyprint lang-yaml">node.attr.size: medium</pre>
</div>
<p>You can also set custom attributes when you start a node:</p>
<div class="pre_wrapper lang-sh">
<pre class="programlisting prettyprint lang-sh">`./bin/elasticsearch -Enode.attr.size=medium</pre>
</div>
</li>
<li class="listitem">
<p>Add a routing allocation filter to the index. The <code class="literal">index.routing.allocation</code>
settings support three types of filters: <code class="literal">include</code>, <code class="literal">exclude</code>, and <code class="literal">require</code>.
For example, to tell Elasticsearch to allocate shards from the <code class="literal">test</code> index to either
<code class="literal">big</code> or <code class="literal">medium</code> nodes, use <code class="literal">index.routing.allocation.include</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT test/_settings
{
  "index.routing.allocation.include.size": "big,medium"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1029.console"></div>
<p>If you specify multiple filters, all conditions must be satisfied for shards to
be relocated. For example, to move the <code class="literal">test</code> index to <code class="literal">big</code> nodes in <code class="literal">rack1</code>,
you could specify:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT test/_settings
{
  "index.routing.allocation.include.size": "big",
  "index.routing.allocation.include.rack": "rack1"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1030.console"></div>
</li>
</ol>
</div>
<h4>
<a id="index-allocation-settings"></a>Index allocation filter settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/index-modules/allocation/filtering.asciidoc">edit</a>
</h4>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">index.routing.allocation.include.{attribute}</code>
</span>
</dt>
<dd>
Assign the index to a node whose <code class="literal">{attribute}</code> has at least one of the
comma-separated values.
</dd>
<dt>
<span class="term">
<code class="literal">index.routing.allocation.require.{attribute}</code>
</span>
</dt>
<dd>
Assign the index to a node whose <code class="literal">{attribute}</code> has <em>all</em> of the
comma-separated values.
</dd>
<dt>
<span class="term">
<code class="literal">index.routing.allocation.exclude.{attribute}</code>
</span>
</dt>
<dd>
Assign the index to a node whose <code class="literal">{attribute}</code> has <em>none</em> of the
comma-separated values.
</dd>
</dl>
</div>
<p>The index allocation settings support the following built-in attributes:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">_name</code>
</p>
</td>
<td valign="top">
<p>
Match nodes by node name
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">_host_ip</code>
</p>
</td>
<td valign="top">
<p>
Match nodes by host IP address (IP associated with hostname)
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">_publish_ip</code>
</p>
</td>
<td valign="top">
<p>
Match nodes by publish IP address
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">_ip</code>
</p>
</td>
<td valign="top">
<p>
Match either <code class="literal">_host_ip</code> or <code class="literal">_publish_ip</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">_host</code>
</p>
</td>
<td valign="top">
<p>
Match nodes by hostname
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">_id</code>
</p>
</td>
<td valign="top">
<p>
Match nodes by node id
</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>You can use wildcards when specifying attribute values, for example:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">PUT test/_settings
{
  "index.routing.allocation.include._ip": "192.168.2.*"
}</pre>
</div>
<div class="console_widget" data-snippet="snippets/1031.console"></div>
</div>
<div class="navfooter">
<span class="prev">
<a href="index-modules-allocation.html">« Index Shard Allocation</a>
</span>
<span class="next">
<a href="delayed-allocation.html">Delaying allocation when a node leaves »</a>
</span>
</div>
</div>

                  <!-- end body -->
                </div>
                <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                  <div id="rtpcontainer" style="display: block;">
                    <div class="mktg-promo">
                      <h3>Most Popular</h3>
                      <ul class="icons">
                        <li class="icon-elasticsearch-white"><a href="https://www.elastic.co/webinars/getting-started-elasticsearch?baymax=default&amp;elektra=docs&amp;storm=top-video">Get Started with Elasticsearch: Video</a></li>
                        <li class="icon-kibana-white"><a href="https://www.elastic.co/webinars/getting-started-kibana?baymax=default&amp;elektra=docs&amp;storm=top-video">Intro to Kibana: Video</a></li>
                        <li class="icon-logstash-white"><a href="https://www.elastic.co/webinars/introduction-elk-stack?baymax=default&amp;elektra=docs&amp;storm=top-video">ELK for Logs &amp; Metrics: Video</a></li>
                      </ul>
                    </div>
                  </div>
                </div>
              </div>
            </div>
          </section>

        </div>


<div id="elastic-footer"></div>
<script src="https://www.elastic.co/elastic-footer.js"></script>
<!-- Footer Section end-->

      </section>
    </div>

<script src="/guide/static/jquery.js"></script>
<script type="text/javascript" src="/guide/static/docs.js"></script>
<script type="text/javascript">
  window.initial_state = {}</script>
  </body>
</html>
